| GITWEB.CONF(5) | Git Manual | GITWEB.CONF(5) |
NAME¶
gitweb.conf - Gitweb (Git web interface) configuration file
SYNOPSIS¶
/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl
DESCRIPTION¶
The gitweb CGI script for viewing Git repositories over the web uses a perl script fragment as its configuration file. You can set variables using "our $variable = value"; text from a "#" character until the end of a line is ignored. See perlsyn(1) for details.
An example:
# gitweb configuration file for http://git.example.org # our $projectroot = "/srv/git"; # FHS recommendation our $site_name = 'Example.org >> Repos';
The configuration file is used to override the default settings that were built into gitweb at the time the gitweb.cgi script was generated.
While one could just alter the configuration settings in the gitweb CGI itself, those changes would be lost upon upgrade. Configuration settings might also be placed into a file in the same directory as the CGI script with the default name gitweb_config.perl — allowing one to have multiple gitweb instances with different configurations by the use of symlinks.
Note that some configuration can be controlled on per-repository rather than gitweb-wide basis: see "Per-repository gitweb configuration" subsection on gitweb(1) manpage.
DISCUSSION¶
Gitweb reads configuration data from the following sources in the following order:
Values obtained in later configuration files override values obtained earlier in the above sequence.
Locations of the common system-wide configuration file, the fallback system-wide configuration file and the per-instance configuration file are defined at compile time using build-time Makefile configuration variables, respectively GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and GITWEB_CONFIG.
You can also override locations of gitweb configuration files during runtime by setting the following environment variables: GITWEB_CONFIG_COMMON, GITWEB_CONFIG_SYSTEM and GITWEB_CONFIG to a non-empty value.
The syntax of the configuration files is that of Perl, since these files are handled by sourcing them as fragments of Perl code (the language that gitweb itself is written in). Variables are typically set using the our qualifier (as in "our $variable = <value>;") to avoid syntax errors if a new version of gitweb no longer uses a variable and therefore stops declaring it.
You can include other configuration file using read_config_file() subroutine. For example, one might want to put gitweb configuration related to access control for viewing repositories via Gitolite (one of Git repository management tools) in a separate file, e.g. in /etc/gitweb-gitolite.conf. To include it, put
read_config_file("/etc/gitweb-gitolite.conf");
somewhere in gitweb configuration file used, e.g. in per-installation gitweb configuration file. Note that read_config_file() checks itself that the file it reads exists, and does nothing if it is not found. It also handles errors in included file.
The default configuration with no configuration file at all may work perfectly well for some installations. Still, a configuration file is useful for customizing or tweaking the behavior of gitweb in many ways, and some optional features will not be present unless explicitly enabled using the configurable %features variable (see also "Configuring gitweb features" section below).
CONFIGURATION VARIABLES¶
Some configuration variables have their default values (embedded in the CGI script) set during building gitweb — if that is the case, this fact is put in their description. See gitweb’s INSTALL file for instructions on building and installing gitweb.
Location of repositories¶
The configuration variables described below control how gitweb finds Git repositories, and how repositories are displayed and accessed.
See also "Repositories" and later subsections in gitweb(1) manpage.
$projectroot
For example, if $projectroot is set to "/srv/git" by putting the following in gitweb config file:
our $projectroot = "/srv/git";
then
and its path_info based equivalent
will map to the path /srv/git/foo/bar.git on the filesystem.
$projects_list
Project list files should list one project per line, with each line having the following format
<URI-encoded filesystem path to repository> SP <URI-encoded repository owner>
The default value of this variable is determined by the GITWEB_LIST makefile variable at installation time. If this variable is empty, gitweb will fall back to scanning the $projectroot directory for repositories.
$project_maxdepth
It is purely performance optimization, originally intended for MacOS X, where recursive directory traversal is slow. Gitweb follows symbolic links, but it detects cycles, ignoring any duplicate files and directories.
The default value of this variable is determined by the build-time configuration variable GITWEB_PROJECT_MAXDEPTH, which defaults to 2007.
$export_ok
$export_auth_hook
our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };
though the above might be done by using $export_ok instead
our $export_ok = "git-daemon-export-ok";
If not set (default), it means that this feature is disabled.
See also more involved example in "Controlling access to Git repositories" subsection on gitweb(1) manpage.
$strict_export
Finding files¶
The following configuration variables tell gitweb where to find files. The values of these variables are paths on the filesystem.
$GIT
$mimetypes_file
$highlight_bin
NOTE: for a file to be highlighted, its syntax type must be detected and that syntax must be supported by "highlight". The default syntax detection is minimal, and there are many supported syntax types with no detection by default. There are three options for adding syntax detection. The first and second priority are %highlight_basename and %highlight_ext, which detect based on basename (the full filename, for example "Makefile") and extension (for example "sh"). The keys of these hashes are the basename and extension, respectively, and the value for a given key is the name of the syntax to be passed via --syntax <syntax> to "highlight". The last priority is the "highlight" configuration of Shebang regular expressions to detect the language based on the first line in the file, (for example, matching the line "#!/bin/bash"). See the highlight documentation and the default config at /etc/highlight/filetypes.conf for more details.
For example if repositories you are hosting use "phtml" extension for PHP files, and you want to have correct syntax-highlighting for those files, you can add the following to gitweb configuration:
our %highlight_ext;
$highlight_ext{'phtml'} = 'php';
Links and their targets¶
The configuration variables described below configure some of gitweb links: their target and their look (text or image), and where to find page prerequisites (stylesheet, favicon, images, scripts). Usually they are left at their default values, with the possible exception of @stylesheets variable.
@stylesheets
push @stylesheets, "gitweb-site.css";
in the gitweb config file. Those values that are relative paths are relative to base URI of gitweb.
This list should contain the URI of gitweb’s standard stylesheet. The default URI of gitweb stylesheet can be set at build time using the GITWEB_CSS makefile variable. Its default value is static/gitweb.css (or static/gitweb.min.css if the CSSMIN variable is defined, i.e. if CSS minifier is used during build).
Note: there is also a legacy $stylesheet configuration variable, which was used by older gitweb. If $stylesheet variable is defined, only CSS stylesheet given by this variable is used by gitweb.
$logo
$favicon
$javascript
The default value is either static/gitweb.js, or static/gitweb.min.js if the JSMIN build variable was defined, i.e. if JavaScript minifier was used at build time. Note that this single file is generated from multiple individual JavaScript "modules".
$home_link
$home_link_str
@extra_breadcrumbs
For example, the following setting produces a breadcrumb trail like "home / dev / projects / ..." where "projects" is the home link.
our @extra_breadcrumbs = (
[ 'home' => 'https://www.example.org/' ],
[ 'dev' => 'https://dev.example.org/' ],
);
$logo_url, $logo_label
Changing gitweb’s look¶
You can adjust how pages generated by gitweb look using the variables described below. You can change the site name, add common headers and footers for all pages, and add a description of this gitweb installation on its main page (which is the projects list page), etc.
$site_name
Can be set using the GITWEB_SITENAME at build time. Unset by default.
$site_html_head_string
$site_header
$site_footer
$home_text
$projects_list_description_width
$default_projects_order
Default value is "project". Unknown value means unsorted.
Changing gitweb’s behavior¶
These configuration variables control internal gitweb behavior.
$default_blob_plain_mimetype
$default_text_plain_charset
$fallback_encoding
@diff_opts
Note that rename and especially copy detection can be quite CPU-intensive. Note also that non Git tools can have problems with patches generated with options mentioned above, especially when they involve file copies ('-C') or criss-cross renames ('-B').
Some optional features and policies¶
Most of features are configured via %feature hash; however some of extra gitweb features can be turned on and configured using variables described below. This list beside configuration variables that control how gitweb looks does contain variables configuring administrative side of gitweb (e.g. cross-site scripting prevention; admittedly this as side effect affects how "summary" pages look like, or load limiting).
@git_base_url_list
Note that per repository configuration can be set in $GIT_DIR/cloneurl file, or as values of multi-value gitweb.url configuration variable in project config. Per-repository configuration takes precedence over value composed from @git_base_url_list elements and project name.
You can setup one single value (single entry/item in this list) at build time by setting the GITWEB_BASE_URL build-time configuration variable. By default it is set to (), i.e. an empty list. This means that gitweb would not try to create project URL (to fetch) from project name.
$projects_list_group_categories
$project_list_default_category
$prevent_xss
$maxload
Set $maxload to undefined value (undef) to turn this feature off. The default value is 300.
$omit_age_column
$omit_owner
$per_request_config
our $per_request_config = sub {
$ENV{GL_USER} = $cgi->remote_user || "gitweb";
};
If $per_request_config is not a code reference, it is interpreted as boolean value. If it is true gitweb will process config files once per request, and if it is false gitweb will process config files only once, each time it is executed. True by default (set to 1).
NOTE: $my_url, $my_uri, and $base_url are overwritten with their default values before every request, so if you want to change them, be sure to set this variable to true or a code reference effecting the desired changes.
This variable matters only when using persistent web environments that serve multiple requests using single gitweb instance, like mod_perl, FastCGI or Plackup.
Other variables¶
Usually you should not need to change (adjust) any of configuration variables described below; they should be automatically set by gitweb to correct value.
$version
our $version .= " with caching";
if you run modified version of gitweb with caching support. This variable is purely informational, used e.g. in the "generator" meta header in HTML header.
$my_url, $my_uri
$base_url
CONFIGURING GITWEB FEATURES¶
Many gitweb features can be enabled (or disabled) and configured using the %feature hash. Names of gitweb features are keys of this hash.
Each %feature hash element is a hash reference and has the following structure:
"<feature_name>" => {
"sub" => <feature-sub (subroutine)>,
"override" => <allow-override (boolean)>,
"default" => [ <options>... ]
},
Some features cannot be overridden per project. For those features the structure of appropriate %feature hash element has a simpler form:
"<feature_name>" => {
"override" => 0,
"default" => [ <options>... ]
},
As one can see it lacks the 'sub' element.
The meaning of each part of feature configuration is described below:
default
Note that it is currently always an array reference, even if feature doesn’t accept any configuration parameters, and 'default' is used only to turn it on or off. In such case you turn feature on by setting this element to [1], and torn it off by setting it to [0]. See also the passage about the "blame" feature in the "Examples" section.
To disable features that accept parameters (are configurable), you need to set this element to empty list i.e. [].
override
Usually given "<feature>" is configurable via the gitweb.<feature> config variable in the per-repository Git configuration file.
Note that no feature is overridable by default.
sub
You wouldn’t need to ever change it in gitweb config file.
Features in %feature¶
The gitweb features that are configurable via %feature hash are listed below. This should be a complete list, but ultimately the authoritative and complete list is in gitweb.cgi source code, with features described in the comments.
blame
This feature can be configured on a per-repository basis via repository’s gitweb.blame configuration variable (boolean).
snapshot
The value of 'default' is a list of names of snapshot formats, defined in %known_snapshot_formats hash, that you wish to offer. Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz compressed tar archive) and "zip"; please consult gitweb sources for a definitive list. By default only "tgz" is offered.
This feature can be configured on a per-repository basis via repository’s gitweb.snapshot configuration variable, which contains a comma separated list of formats or "none" to disable snapshots. Unknown values are ignored.
grep
This feature can be configured on a per-repository basis via repository’s gitweb.grep configuration variable (boolean).
pickaxe
The pickaxe search is described in git-log(1) (the description of -S<string> option, which refers to pickaxe entry in gitdiffcore(7) for more details).
This feature can be configured on a per-repository basis by setting repository’s gitweb.pickaxe configuration variable (boolean).
show-sizes
This feature can be configured on a per-repository basis via repository’s gitweb.showSizes configuration variable (boolean).
patches
This feature can be configured on a per-repository basis via repository’s gitweb.patches configuration variable (integer).
avatar
Currently available providers are "gravatar" and "picon". Only one provider at a time can be selected (default is one element list). If an unknown provider is specified, the feature is disabled. Note that some providers might require extra Perl packages to be installed; see gitweb/INSTALL for more details.
This feature can be configured on a per-repository basis via repository’s gitweb.avatar configuration variable.
See also %avatar_size with pixel sizes for icons and avatars ("default" is used for one-line like "log" and "shortlog", "double" is used for two-line like "commit", "commitdiff" or "tag"). If the default font sizes or lineheights are changed (e.g. via adding extra CSS stylesheet in @stylesheets), it may be appropriate to change these values.
email-privacy
highlight
This feature can be configured on a per-repository basis via repository’s gitweb.highlight configuration variable (boolean).
remote_heads
This feature can be configured on a per-repository basis via repository’s gitweb.remote_heads configuration variable (boolean).
The remaining features cannot be overridden on a per project basis.
search
Project specific override is not supported.
forks
If the project list is taken from a file ($projects_list points to a file), forks are only recognized if they are listed after the main project in that file.
Project specific override is not supported.
actions
The "default" value consists of a list of triplets in the form ‘("<label>", "<link>", "<position>")` where "position" is the label after which to insert the link, "link" is a format string where %n expands to the project name, %f to the project path within the filesystem (i.e. "$projectroot/$project"), %h to the current hash ('h’ gitweb parameter) and ‘%b` to the current hash base ('hb’ gitweb parameter); ‘%%` expands to '%’.
For example, at the time this page was written, the http://repo.or.cz Git hosting site set it to the following to enable graphical log (using the third party tool git-browser):
$feature{'actions'}{'default'} =
[ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];
This adds a link titled "graphiclog" after the "summary" link, leading to git-browser script, passing r=<project> as a query parameter.
Project specific override is not supported.
timed
Project specific override is not supported.
javascript-timezone
The value is a list of three values: a default time zone (for if the client hasn’t selected some other time zone and saved it in a cookie), a name of cookie where to store selected time zone, and a CSS class used to mark up dates for manipulation. If you want to turn this feature off, set "default" to empty list: [].
Typical gitweb config files will only change starting (default) time zone, and leave other elements at their default values:
$feature{'javascript-timezone'}{'default'}[0] = "utc";
The example configuration presented here is guaranteed to be backwards and forward compatible.
Time zone values can be "local" (for local time zone that browser uses), "utc" (what gitweb uses when JavaScript or this feature is disabled), or numerical time zones in the form of "+/-HHMM", such as "+0200".
Project specific override is not supported.
extra-branch-refs
$feature{'extra-branch-refs'}{'default'} =
['sandbox', 'wip', 'other'];
This feature can be configured on per-repository basis after setting $feature{extra-branch-refs}{override} to true, via repository’s gitweb.extraBranchRefs configuration variable, which contains a space separated list of refs. An example:
[gitweb]
extraBranchRefs = sandbox wip other
The gitweb.extraBranchRefs is actually a multi-valued configuration variable, so following example is also correct and the result is the same as of the snippet above:
[gitweb]
extraBranchRefs = sandbox
extraBranchRefs = wip other
It is an error to specify a ref that does not pass "git check-ref-format" scrutiny. Duplicated values are filtered.
EXAMPLES¶
To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and "zip" snapshots), while allowing individual projects to turn them off, put the following in your GITWEB_CONFIG file:
$feature{'blame'}{'default'} = [1];
$feature{'blame'}{'override'} = 1;
$feature{'pickaxe'}{'default'} = [1];
$feature{'pickaxe'}{'override'} = 1;
$feature{'snapshot'}{'default'} = ['zip', 'tgz'];
$feature{'snapshot'}{'override'} = 1;
If you allow overriding for the snapshot feature, you can specify which snapshot formats are globally disabled. You can also add any command-line options you want (such as setting the compression level). For instance, you can disable Zip compressed snapshots and set gzip(1) to run at level 6 by adding the following lines to your gitweb configuration file:
$known_snapshot_formats{'zip'}{'disabled'} = 1;
$known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];
BUGS¶
Debugging would be easier if the fallback configuration file (/etc/gitweb.conf) and environment variable to override its location (GITWEB_CONFIG_SYSTEM) had names reflecting their "fallback" role. The current names are kept to avoid breaking working setups.
ENVIRONMENT¶
The location of per-instance and system-wide configuration files can be overridden using the following environment variables:
GITWEB_CONFIG
GITWEB_CONFIG_SYSTEM
GITWEB_CONFIG_COMMON
FILES¶
gitweb_config.perl
/etc/gitweb.conf
/etc/gitweb-common.conf
SEE ALSO¶
gitweb/README, gitweb/INSTALL
GIT¶
Part of the git(1) suite
| 11/20/2023 | Git 2.43.0 |